home *** CD-ROM | disk | FTP | other *** search
/ The Original Shareware 1.1 / The Original Shareware (WeMake CDs)(Volume 1.1)(CDs, Inc)(1993).iso / 25 / arj210.exe / arj / REARJ.DOC < prev    next >
Text File  |  1991-05-28  |  19KB  |  499 lines
  1.  
  2.  
  3.  
  4.  
  5.      User's Manual for the REARJ archive conversion program,   May 1991
  6.  
  7.  
  8.  
  9.     REARJ software and manual copyright (c) 1991 by Robert K Jung.
  10.     All rights reserved.
  11.  
  12.     REARJ version 1.21 release
  13.  
  14.  
  15.  
  16.      INTRODUCTION:
  17.  
  18.      REARJ is an archive conversion program designed to facilitate the
  19.      conversion of LZH, ZIP, PAK, ARC, DWC, HYP, LZS, and ZOO archives to
  20.      the ARJ format.  In addition, this converter has been designed to
  21.      convert to any of the aforementioned archive formats.
  22.  
  23.  
  24.      MAJOR FEATURES:
  25.  
  26.      Supports all major archiver programs (PAK, LHARC, PKZIP, ZOO,
  27.      ARJ, PKPAK, DWC, HYPER, LARC, LHA).
  28.  
  29.      Supports file attributes within archives.
  30.  
  31.      Supports directories within archives.
  32.  
  33.      Supports converting archives within archives (ZIPs in a ZIP).
  34.  
  35.      Ensures reliable archive conversion with a file count and total
  36.      size check.
  37.  
  38.      Supports the use of virus checkers.
  39.  
  40.      Supports pathnames with drive letters.
  41.  
  42.      Is command line driven.
  43.  
  44.      Supports recursive scanning through subdirectories.
  45.  
  46.      Optional logging of conversions.
  47.  
  48.      Simulation option.
  49.  
  50.  
  51.      A WORD OF CAUTION:
  52.  
  53.      If you plan to convert many archives at one time, it is STRONGLY
  54.      suggested that you make a backup of your hard disk.  This is a wise
  55.      precaution to take anytime that you make major modifications to data
  56.      on your hard disk drive.
  57.  
  58.      REARJ will not work properly for those archivers/archives that produce
  59.      absolute directory paths when extracting.    In other words, REARJ
  60.      expects to find all extracted data in its created temporary directory.
  61.  
  62.      I have discovered that LHA using the "x" command does not return an
  63.      error when encountering a DISK FULL situation.  This will cause data
  64.      loss!!!  You should scan the log file after a conversion to look for
  65.      any major archive size differences.
  66.  
  67.      REARJ's default configuration does not support volume labels.  You can
  68.      modify the ZIP and ARJ configurations by adding -$D where "D" is a
  69.      drive where the archivers can change/access the volume label.  Please
  70.      note that this will only work correctly when every archive to be
  71.      converted has a volume label in it.  Volumes that do not have volume
  72.      labels will be converted into one with a volume label!!!
  73.  
  74.      The archiver executables must be located in the DOS PATH directories.
  75.      This is due to REARJ creating and using a temporary directory.
  76.  
  77.      If you have changed the MS-DOS switch character from "/" to another
  78.      character via an undocumented MS-DOS interrupt or the TurboC
  79.      setswitchar() function, REARJ may not work properly with the default
  80.      REARJ.CFG configuration file.
  81.  
  82.      The most thorough testing was done with ARJ as the target format and
  83.      ZIP as the original format.  In any case, you should verify that the
  84.      extract commands of your favorite archive formats in the configuration
  85.      file are correct.    The extract commands are the most important to get
  86.      right because REARJ has a built-in verification procedure to ensure
  87.      that the ADD commands executed properly.
  88.  
  89.      Be sure you have enough disk space on your working directory to
  90.      extract the largest archive that you want to convert!!!
  91.  
  92.  
  93.      The versions of archivers tested:
  94.  
  95.      ARJ   1.00, 1.10, 2.00, 2.10
  96.      LHA   2.12
  97.      PAK   2.51
  98.      PKZIP 1.10
  99.      PKPAK 3.61
  100.      ZOO   2.01
  101.      DWC   A5.01
  102.      LARC  3.33
  103.      HYPER 2.5
  104.  
  105.  
  106.      INSTALLATION:
  107.  
  108.      Copy REARJ.EXE and REARJ.CFG to one of the PATH directories.  They do
  109.      not have to be placed in the same directory.  The PATH directories are
  110.      usually set by the PATH command in your AUTOEXEC.BAT file.
  111.  
  112.      Be sure the archivers are installed in a PATH directory.
  113.  
  114.  
  115.      OPERATION OF REARJ:
  116.  
  117.      REARJ will build a temporary directory in the current directory and
  118.      extract the archive(s) to this directory.    REARJ will then build the
  119.      target archive(s) with the files in this directory.  If the target
  120.      archiver does not support reading of hidden or system files, REARJ
  121.      will reset those bits and then re-archive the files without those
  122.      attributes.  If the original archive has directories in it, REARJ will
  123.      extract it with full paths and re-archive it with full paths if the
  124.      target archiver supports directories.  In this case, if the archiver
  125.      does not support directories, REARJ will skip converting this archive.
  126.  
  127.      If the "/a" option has been selected, REARJ will execute REARJ to
  128.      convert any internal archives of the same type to the target format.
  129.      Any "/s" option will be carried over to the recursive REARJ command.
  130.  
  131.      As an extra test, REARJ will count the files extracted from the
  132.      original archive and total their sizes.  Then REARJ will extract the
  133.      new archive and count the files and total the sizes.  If the count and
  134.      size do not match, REARJ will skip converting the archive.
  135.  
  136.      REARJ assumes that the supported archivers will pass a non-zero error
  137.      code when there is an operation failure.
  138.  
  139.  
  140.      COMMAND SYNTAX:
  141.  
  142.      REARJ [switch options] filespec(s) or wildspec(s)
  143.  
  144.      You can specify one or more filespecs on the command line.  These
  145.      filespecs can have paths and wildcards.  Up to 100 filespecs can be
  146.      accepted by REARJ.  If you specify *.* as a wildspec, REARJ will look
  147.      at all filenames, but will skip those filenames not ending in standard
  148.      archive suffixes.    If you specify the /r switch, REARJ will look for
  149.      filenames matching the filespec(s) in the current directory and all
  150.      subdirectories of the current directory.
  151.  
  152.      If you want to use a RAMDRIVE as the temporary directory, you must
  153.      make the RAMDRIVE the current drive and directory and execute REARJ
  154.      commands from there.
  155.  
  156.      The switch options and filespecs can be entered in any order.  REARJ
  157.      uses the default MS-DOS switch character "/".  REARJ uses the Turbo
  158.      C++ function getswitchar() to determine the MS-DOS switch character.
  159.      If the switch character is "-", REARJ will translate any UNIX style
  160.      pathnames to MS-DOS syntax ("dir/file" to "dir\file").
  161.  
  162.  
  163.      SWITCH OPTIONS:
  164.  
  165.      /a - convert archives within archives
  166.  
  167.       This option causes REARJ to recursively execute REARJ to convert
  168.       any archives of the original type found within the original
  169.       archive (ex. ZIPs within a ZIP).  This option requires additional
  170.       memory to execute successfully.
  171.  
  172.       NOTE!!!  When using this option, REARJ.EXE and REARJ.CFG must be
  173.       installed in a DOS PATH directory because the recursive REARJ
  174.       will be executed within a temporary directory and NOT in the
  175.       original directory.
  176.  
  177.      /d - delete the original archive
  178.  
  179.       This option causes REARJ to delete the original archive after a
  180.       successful conversion to the target format.  This option will NOT
  181.       delete read-only archives.
  182.  
  183.      /e - do not return error if no archives were found
  184.  
  185.       This option is used by the internal recursive REARJ.    This option
  186.       will cause REARJ to return a zero exit code if no matching
  187.       archives were found.    Usually, REARJ returns a non-zero exit
  188.       code for this condition.
  189.  
  190.      /i - check program integrity
  191.  
  192.       This option causes REARJ to validate the REARJ program on disk.
  193.       If you are using a pre-3.0 MS-DOS revision, you will have to
  194.       specify the full program name as in "REARJ /i\util\rearj.exe".
  195.  
  196.      /l - write conversion data to log file
  197.  
  198.       This option causes REARJ to open a log file and record each
  199.       successful conversion in the log file.  The default log file name
  200.       is REARJ.LOG.  You can specify the log file name as in
  201.       "REARJ /lfilename *.ZIP".  If the log file already exists, REARJ
  202.       will append logging data to it.
  203.  
  204.      /o - overwrite existing target archive
  205.  
  206.       This switch is used to delete already existing target archives.
  207.       This is not used for updating archives.  Use the /u option for
  208.       updating an archive.
  209.  
  210.      /q - query for each archive to convert
  211.  
  212.       This switch causes REARJ to pause and prompt the user for
  213.       permission to convert individual archives.  Note that REARJ will
  214.       not prompt when skipping archives.
  215.  
  216.      /r - recurse through subdirectories
  217.  
  218.       This switch causes REARJ to look for archives in all included
  219.       subdirectories as well as in the current directory.  This switch
  220.       allows the user to convert all archives on a hard disk with one
  221.       command.
  222.  
  223.      /s - skip verify of file count and total size
  224.  
  225.       Skip the overhead of the file count and total size verification
  226.       process.  This verification costs an extra extraction, but this
  227.       check is worth the time, especially when converting a large
  228.       number of archives.
  229.  
  230.      /t - specify the target archive type
  231.  
  232.       The default target archive format is normally ARJ.  This can be
  233.       changed by building an external REARJ.CFG file.  The first
  234.       archive type is always the default format.  To override the
  235.       default format, the user can specify the /t switch as in
  236.       "REARJ *.ZIP /tlzh".    The previous example has specified that LZH
  237.       is the target format.
  238.  
  239.      /u - allow update of archive with backup
  240.  
  241.       This switch is used to re-archive an archive, possibly to take
  242.       advantage of improved compression.  The original archive is
  243.       backed up by renaming it with the backup suffix which by default
  244.       is "BAK".  You may specify another backup suffix with the /u
  245.       option as in "REARJ *.ARJ /uar$" where the backup suffix is
  246.       "ar$".  Since this option creates a brand new archive, archive
  247.       comments will be lost.  Do NOT specify a "." in the suffix.
  248.  
  249.      /v - execute configured command on extracted files
  250.  
  251.       This switch is used to execute a configure command on the files
  252.       extracted from the original archive.    The intent is to allow
  253.       virus scanning of the archive contents.  The command must be
  254.       specified in the REARJ.CFG file.
  255.  
  256.       The command may be placed in the REARJ.CFG file by inserting one
  257.       line ahead of the archive commands.  The line must start with the
  258.       word "VIRUS" followed by a blank and the external command.
  259.  
  260.       Example:  VIRUS scan /nomem *.*
  261.  
  262.       If the invoked command returns a non-zero error code, REARJ will
  263.       skip the conversion of that archive and log the error as code 13.
  264.  
  265.       REARJ *.* /v
  266.  
  267.      /x - exclude filenames or wildnames from the conversion process
  268.  
  269.       You can exclude one or more files from the conversion process.
  270.       The filenames can contain wildcards.
  271.  
  272.       REARJ *.ZIP /xONE.ZIP /xTWO.ZIP
  273.  
  274.      /z - simulate conversion process
  275.  
  276.       This switch causes REARJ to simulate the conversion process.    No
  277.       archives will be extracted, built, or deleted.
  278.  
  279.  
  280.      EXAMPLES:
  281.  
  282.      REARJ *.ZIP           this converts all ZIP files in the current
  283.                    directory to ARJ files.
  284.  
  285.      REARJ *.ZIP *.ARC           this converts ZIP and ARC files to ARJ
  286.                    files.
  287.  
  288.      REARJ SOFT.ZIP           this converts only SOFT.ZIP to SOFT.ARJ.
  289.  
  290.      REARJ *.ZIP /d /l           this converts ZIP files with logging and
  291.                    deletion of each original archive upon
  292.                    successful conversion.
  293.  
  294.      REARJ *.ARC /r           this converts all ARC files in the current
  295.                    directory and in subdirectories of the
  296.                    current directory to ARJ files.
  297.  
  298.      REARJ SOFT.ARJ /tZIP       this converts SOFT.ARJ to SOFT.ZIP.
  299.  
  300.      REARJ *.ARJ /u           re-archive all ARJ archives.
  301.  
  302.      REARJ *.* /v           re-archive all archives and execute
  303.                    configured command on extracted files
  304.  
  305.  
  306.      EXTERNAL CONFIGURATION FILE
  307.  
  308.      REARJ comes with a configuration file, REARJ.CFG, which supports
  309.      conversion between the ARJ, ARC, LZH, PAK, ZIP, DWC, LZS, HYP, and ZOO
  310.      formats.  The commands PKPAK and PKUNPAK are used for ARC files.  The
  311.      command LHA is used for LZH files.  You can change these defaults by
  312.      editing the configuration file.
  313.  
  314.      The format of the configuration file is fairly simple.
  315.  
  316.      The first line can optionally specify an external command to be
  317.      executed by REARJ when the "/v" option is selected.  This line must
  318.      start with the word "VIRUS" minus the quotes, followed by a space,
  319.      followed by the external command.
  320.  
  321.      Example:  VIRUS SCAN /nomem *.*
  322.  
  323.      If you do not want to configure this item, DO NOT insert a blank line.
  324.  
  325.      Each archive format requires four lines in the file.
  326.  
  327.      The first line is the format suffix.
  328.  
  329.      The second line is the archive ADD command with a %s in the place of
  330.      the archive name.    Any other percent signs in the command must be
  331.      preceded by "\" as in "\%".  The ADD command should support directory
  332.      inclusion and reading of hidden and/or system files.  REARJ will parse
  333.      this command line using the space character as the token separator.
  334.  
  335.      If your ADD command requires DOS piping as the ZOO archiver requires,
  336.      you must precede the ADD command with the text "COMMAND /C ".
  337.  
  338.      Example:  ARJ a -a -r -jt %s
  339.            COMMAND /C STUFF *.* | ZOO aI %s
  340.  
  341.      The third line is the archive EXTRACT command with a %s in the
  342.      place of the archive name.  Any other percent signs in the command
  343.      must be preceded by "\" as in "\%".  The EXTRACT command should
  344.      support directory recreation if the archive contains directories.
  345.      The extraction of directories must be to child directories within the
  346.      current directory.  REARJ will parse this command line using the space
  347.      character as the token separator.
  348.  
  349.      If your EXTRACT command requires DOS piping, you must precede the
  350.      EXTRACT command with the text "COMMAND /C ".  Beware that command exit
  351.      codes are not passed back to REARJ when using COMMAND /C.
  352.  
  353.      The fourth line contains the letters "A" and/or "D" or no letters.
  354.      The "A" stands for the ability to process files with the hidden and/or
  355.      system attribute.    The "D" stands for full support of directory trees
  356.      within archives.  No letters (blank line) stands for no support for
  357.      hidden or system files or for archive containing directories.
  358.  
  359.      There must be NO EXTRA blank lines or comments in the file.  You may
  360.      use leading blanks for clarity.
  361.  
  362.      The first format type declared in the configuration file is used by
  363.      REARJ as its default target format.   REARJ.CFG is currently setup
  364.      with ARJ as its default target format.
  365.  
  366.      The following is the current REARJ.CFG configuration:
  367.  
  368.      VIRUS scan /nomem *.*
  369.      ARJ
  370.       ARJ a -a+ -r+ -y+ -jt+ %s
  371.       ARJ x -y+ %s
  372.       AD
  373.      ZIP
  374.       PKZIP -a -r -p -wHS %s
  375.       PKUNZIP -d %s
  376.       AD
  377.      ARC
  378.       PKPAK -a %s
  379.       PKUNPAK %s
  380.  
  381.      LZH
  382.       LHA a /a+ /r+ /x+ %s
  383.       LHA x /a+ %s
  384.       AD
  385.      PAK
  386.       PAK a /i %s
  387.       PAK e /path %s
  388.       AD
  389.      ZOO
  390.       COMMAND /C STUFF *.* | ZOO aI %s
  391.       ZOO x.// %s *
  392.       D
  393.      HYP
  394.       HYPER -a -r -p %s
  395.       HYPER -x -p %s .
  396.       AD
  397.      DWC
  398.       DWC a %s *.*
  399.       DWC e %s
  400.  
  401.      LZS
  402.       LARC a /r %s *.*
  403.       LARC e /x %s *.*
  404.       D
  405.  
  406.      If you use a different archiver program, you will need to either
  407.      rename the program to one of the supported ones or you will need to
  408.      modify the installed REARJ.CFG file.
  409.  
  410.      DWC does not allow duplicate filenames even within a directory
  411.      structure, so "D" is not set for DWC.
  412.  
  413.      LARC may or may not work correctly for archives with directories.    I
  414.      was unable to stop LARC from querying on making directories.
  415.  
  416.      If your original archive format supports extraction to absolute
  417.      directory paths as opposed to relative directory paths and you have
  418.      such archives containing absolute paths, you should not put directory
  419.      extraction in the REARJ.CFG file.
  420.  
  421.  
  422.      LOG FILE DATA
  423.  
  424.      When logging is enabled, REARJ will log the action on each selected
  425.      file.  For successful conversions, REARJ logs the date-time, target
  426.      archive type, original archive size, new archive size, bytes saved,
  427.      and original archive name.
  428.  
  429.      When selected files are skipped for any reason, REARJ will log an
  430.      entry in the log file (when logging is enabled) which specifies the
  431.      reason code for skipping the file.  The following are the codes:
  432.  
  433.      1    = File not found
  434.      2    = File is not a configured archive type
  435.      3    = Target archive already exists
  436.      4    = Not enough disk space       (currently unimplemented)
  437.      5    = User skipped or user did not select update option
  438.      6    = UNPACK error
  439.      7    = PACK error
  440.      8    = Target cannot support directories
  441.      9    = Wrong file count
  442.      10 = Wrong total size
  443.      11 = Internal archive REARJ error
  444.      12 = Rename archive error
  445.      13 = Invoked /v command error (found a virus?)
  446.  
  447.  
  448.      LICENSE POLICY:
  449.  
  450.      REARJ has an unusual license policy.
  451.      Please refer to the LICENSE.DOC for license information.
  452.  
  453.  
  454.      TECHNICAL SUPPORT:
  455.  
  456.      Please report any bugs.  I will TRY to fix them.
  457.  
  458.      I can be reached at:
  459.  
  460.      Robert Jung at Wonderland BBS           (508) 663-6220
  461.  
  462.      Robert Jung at Dimensional Crossroads BBS (508) 427-5379
  463.  
  464.      Robert Jung at Bay State BBS           (617) 598-6646
  465.  
  466.      Robert Jung at FIDONET address:  1:16/390.7
  467.  
  468.      Robert Jung in the COMPRESS (ILINK), LHARC / COMPRESSIONS
  469.      (SMARTNET), SHARE (RIME) or ARCHIVERS (RELAYNET) echo conferences.
  470.  
  471.      2606 Village Road West
  472.      Norwood, Massachusetts 02062
  473.      USA
  474.  
  475.      Internet address:    robjung@world.std.com  (Checked daily)
  476.  
  477.      Compuserve users can enter   >INTERNET: robjung@world.std.com
  478.      at the "Send to" prompt.  I prefer CompuServe users to send mail
  479.      to this address as opposed to my CompuServe userid below.
  480.  
  481.      CompuServe userid: 72077,445  (Checked infrequently)
  482.  
  483.  
  484.      HISTORY:
  485.  
  486.      1.21 - Added error message when executables are not in DOS PATH.
  487.         Added further tests to rename function to avoid bugs in Windows.
  488.         Added /v option to support virus scanning.
  489.         Allowed more heap space in link of REARJ.
  490.  
  491.      1.20 - Fixed path processing with drive letters.  Fixed alternate drive
  492.         processing.  Removed disk space checking.
  493.  
  494.         Fixed REARJ.CFG for LZH and HYP archives.
  495.         Added /u option.  Changed /o option.
  496.  
  497.      end document
  498.  
  499.